﻿Roller

What Is It?

    This plug-in is written for execution by GIMP. The plug-in is designed to create image compositions like wallpaper, image boards, or collages.

How To Use Roller

    The plug-in is accessed through the menus: / Filters / Render.

    1) Have any images opened in GIMP that you'd like to compose. Note that Roller will remove a selection from a used image.

    2) Select from the menu / Filter / Roller.

    3) The plug-in starts by creating a main window. Here you can create formats, save presets, choose a backdrop style, show a preview, and define the resolution of the output rendered image.

    4) Create A Format

        Select the New Format button. This will create a new format and open up the Format window so that you can modify the format. After you've created a format. You will see it show up in the list box to the left of the format buttons. Selecting a format in this list will allow you to edit or delete the format.

    5) Select A Backdrop Style

        The Backdrop Style applies to the backdrop layer. The Backdrop Style uses material from a Backdrop Image to create the backdrop. If no image is selected, a white flood fill method is substituted.

        Note that a Backdrop Image's transparency and opacity are preserved.

    6) Set The Composition Size

        Enter the resolution of the output image in the width and height text entries. The plug-in's default resolution is the screen resolution.

    7) Prepare To Render

        Select the Show Preview button to see a sketch-up of the rendered composition. Select different options in the Preview Options menu in order to gain insight into your composition.

    8) Save Your Template

        Next to the preset menu is a Save button. Selecting this button is how you can save the current form.

    3.6) Render Your Composition

        Select the Render button. A new image will be created if the preview hasn't already created one. The plug-in will start by creating the backdrop, and then move to creating formats. The formats are created from the bottom-up in the Format Stack.

    3.7) Save Your Result

        I recommend exporting the file using the ‘.PNG’ file type for superior image quality. Saving the file as the '.xcf' file type is super if you want to preserve the layer structure.

What About
    Windows

        Pressing Enter accepts any changes made, unless a button is in focus. Pressing Esc closes a window without accepting any changes.

    Main Window
        Form Group
            Format Stack List-box

                Formats are listed here. New formats are added to the bottom of the stack. The order of the stack reflects the layer order of the formats in the render image.

            New Format Button

                Selecting this button creates a new default format and opens the Format window.

            Edit Format Button

                Selecting this button opens up the Format window for the current selected format in the Format Stack.

            Del Format Button

                This button will delete a selected format without delay.

            Move Up (↑) Button

                Activating this button moves the current selection in the Format Stack up one row. If the selection is at the top of the list, the selection moves to the bottom of the list.

            Move Down (↓) Button

                Activating this button moves the current selection in the Format Stack down one row. If the selection is at the bottom of the list, the selection moves to the top of the list.

            Preset Menu

                This drop-down menu will list any presets that are available such as previously saved presets.

            Save Button

                These buttons open a save preset window.

            Delete Button

                These buttons open a delete preset window.

        Backdrop Group
            Backdrop Style Menu

                The backdrop will be rendered with the chosen option.

            Backdrop Image

                The backdrop styles uses the material chosen from this menu.

        Layout Group
            Show Layout Button

                Selecting this button will create a simulated render.

            Layout Options Menu

                In this pop-up menu, eight options for the layout can be switched on and off. A check-mark is used to signify a selected option.

                The Cell Margins option will display these margins as rectangles.

                The Coordinates options will display the top-left coordinates of an image.

                The Corners option displays an image's box coordinates.

                The Dimensions option will display the dimensions for each image.

                The Grid option will draw lines corresponding to the row and column counts.

                The Layer Margins option will display these margins as rectangles.

                The Name option display an image's title.

                The Ratios option displays a calculated ratio where the center (x, y) of an image is divided by the (w, h) dimensions of the composition size.

        Resolution Group
            Width and Height Entries

                These are numeric values that define the output size of the rendered image in pixels.

        Process Group

            Manual, Auto: Last Used, Auto: Randomized Radio-Buttons

                These three options change user-interaction and automation.

                The Manual option allows the user to set the values of the Backdrop Style and 3D Effect interactively through a series of dialogs.

                The Auto: Last Used option loads the style and effect values from the current session data. This would be the last used values. The dialogs are then skipped.

                The Auto: Randomized option randomizes the style and effect values, and dialogs are skipped.

    Format Window
        Format Layer Group
            Format Name Entry

                This is a alphanumeric entry that gives the format a name. This name is displayed in the Format Stack.

            3D Effect Menu

                These effects are applied to and around the format's image layer. The purpose of an effect is to add a dimension to the image, and thus, the render.

            Show in the Layout Preview Checkbox

                If checked the format layer will be included in a layout-preview. Layout-previews are generated when the user selects the "Show Layout" button. If you notice that the layout-preview is too cluttered with layers, then this option will allow you to remove layers from the layout-preview.

        Layer Cell Group
            Rows Spin-Button

                This value creates corresponding rows on the layer.

            Columns Spin-Button

                This value creates corresponding columns on the layer.

            Per Cell Checkbox

                When checked, a Merge Cells button will be enabled. Clicking this button opens the Merge Cells window. Turning off the Per Cell's check-mark causes merged cells to reset.

        Image Placement Group
            Resize Menu

                These options determine how an image is placed into a cell. The default is Locked (for locked proportions).

                Locked means that an image's aspect ratio is locked. If needed, an image will scale to fit into a cell, but the image's proportions will stay the same.

                If Fill Cell is selected, an image will be resized so that it fills the dimensions of its assigned cell.

                If None is selected, the image won't be resized during the transfer. If needed, a selection will limit the image to its cell size. The selection uses the Horizontal and Vertical settings to further define the selection.

                The Trim option will downsize an image to fit a cell by trimming the fat from the image before resizing. Fat is determine to be lesser size of two rectangles. Each rectangle is determined by the result of fitting the image into its cell by an x or y axis.

                Trim is useful to fill a cell entirely without distorting the image proportions. Justification options play a part in which part of an input image gets trimmed, just like with the None option.

            Horizontal Menu

                In the output, image(s) will arrange themselves on the x-axis per this value.

            Vertical Menu

                In the output, image(s) will arrange themselves on the y-axis per this value.

            Image Menu

                This determines which images are placed on a layer. There are four directions that this option can take you.

                1) Next option: This option will assign an image to a cell starting from the first-opened image until the last opened image is used by this option's index.

                2) Image name option: You can assign an image to a cell by the image's name.

                3) Image order option: You can assign an image to a cell by its order in the image list. This is useful for templates.

                4) None option: The cell(s) will not have an image.

            Per Cell Checkbox

                When checked, a Placement... button will show. Clicking this button opens the Image Placement window. Turning off the Per Cells check-mark causes any per cell placements to reset.

        Image Property Group
            Flip Horizontal Checkbox

                This will flip the contents of an image from left to right.

            Flip Vertical Checkbox

                This will flip the contents of an image from top to bottom.

            Blur Behind Spin-Button

                If this value is greater than zero, then the effect is applied. Blur Behind will create a background layer, a duplicate of the current background, with the areas behind an image with this setting applied, blurred.

                With opaque images, this setting will not produce any visible results. So, Blur Behind is used behind images with transparency. The idea here is to create a blurred-translucent effect for the image's appearance.

                Another example of Blur Behind is Clear Frame. FYI, Clear Frame is using a blur setting of 16.

            Rotate Spin-Button

                This will rotate an image from zero to 359 degrees.

            Opacity Spin-Button

                This will set an image's opacity. An opacity of zero will cause the cell(s) to not display an image.

            Per Cell Checkbox

                When checked, a Properties... button will show. Clicking this button opens the Properties window. Turning off the Per Cells check-mark causes any per cell properties to reset.

        Layer Margins
            Four Spin-Buttons:

                These values form an invisible barrier around the layer. These values reshape the canvas entirely. The come in two flavors: fixed-value and percentage-of-layer. A fixed-value is simply value will stay the same within the confines of the program. On the other hand, the percentage-of-layer value, is dynamic, in that a given margin will be calculated relative to the layer's dimension.

        Cell Margins
            Four Spin-Buttons

                These values form spaces around each cell in a layer. They can cause an image to be reduced in size in the final output. Their values are in pixels. Just like the layer margins, cell margins are fixed and dynamic. The difference is that the cell margins calculate relative to the cell's allocation size which is the cell size before margins are subtracted.

                If layer or cell margins exceed the cell size, they are limited to provide a single pixel for the image. The code will view the margin data as basically invalid, and will adjust the margins to center the image pixel. This will look strange if you have the margins on display in the Layout Preview as the squeezed-margins display as a single line.

            Per Cell Checkbox

                When checked, a Margins button will show. Clicking this button opens the Cell Margins window. Turning off the Per Cell's check-mark causes per cell values used by Cell Margins to reset.

    Per Cell Windows

        The term Per Cell windows refers to the associated windows created from the Format window after the Per Cell checkbox is checked. When one of these check-boxes is checked, a corresponding cell table will initialize to the settings in the Format window.

    Merge Cells Window

        In this window, a cell grid is shown with each cell having connectors. Connectors are plus and minus buttons.

        When plus buttons are clicked, they connect two or more cells. Cell groups can be merged or sliced by these connectors. A merge happens when two groups are on both sides of the connector. A slice occurs when a group and a single cell are connected, and the result expands (slices) through another group.

        Minus connectors appear in merged cell groups and are the opposing function to the plus connectors. Clicking a minus connector will split a group along either the vertical or horizontal axis depending on the location of the connector.

        The cells will also display their pixel size with margins computed, and their coordinates.

    Image Placement Window

        In this window, the cell structure defined in the Grid group will appear with placement controls.

        In the Per Cell windows, a No Picture result can appear. This happens when the Image menu is set to None or if the cell's opacity property is set to zero.

    Properties Window

        In this window, the four image properties appear for the current cell structure as defined in the Grid group and Placement group.

    Margins Window

        In this window, the four image margins appear for the current cell structure as defined in the Grid group and Placement group.

    Preset Save Windows

        These windows will allow you to name a preset (Form or Format variables) before saving the file. They also show you where the preset file is going to be saved.

    Options Window
        Angle

            This is the size of wedge in the Floor Sample style. Angles that divide into 360 evenly will not have overlapping wedges in the render.

        Backdrop Blur

            This is the amount of blur effect to apply to the backdrop image.

        Blend

            In Rocky Landing, the greater this value, the greater the output material will appear homogenous.

        Border Type

            Rounded borders will have rounded corners end expansions. Angular borders will be square or have hard angles.

        Border Width

            The width of an effect's border. Borders expand from an image selection by this amount.

        Cell Gap

            This correlates with a cell count from left to right, top to bottom, between cell assignments. So a cell gap of two, will assign every other cell a placement when using the Evenly Distributed option.

        Color Buttons

            These buttons have color on their face and allow the user to choose a color. A color-chooser pop-out dialog appears when the button is activated.

        Composition Border Width

            A positive value will create a border around the edge of the render layer.

        Direction

            Defines the spin direction of the maze.

        Emboss

            The Rainbow Valley output will be embossed which gives the output a 3D appearance.

        Fit image to render

            When this option is checked, the source image will be shaped to the size of the render. If this option is off, the source image will not be resized, but may be clipped at the edges of the render if the source image exceeds the render size.

        Gap Type

            If the gap type is random, cells are chosenly randomly for connectors and mazes. If the Evenly Distributed is selected, the cell gap value is used to determine cell displacement across the maze quarter until the scatter count is reached.

        Gradient

            This is a list of available gradients found in the GIMP installation.

        Gradient Type

            These are different ways that a gradient can be drawn. Each type distributes a gradient's colors in a different pattern.

        Inlay Blur

            This is amount of blur that is used for the image edge shadow which will lie within the image itself.

        Inherit Opacity

            When borders and shadows are created, they use an image's opacity for their selections. This opacity, by default, is inherited. So an opaque image will have an opaque border, and a translucent image will have a shadow that falls directly behind it.

            The Make Opaque option causes the borders and shadow to see an image as opaque, and the effect's appearance will change. With shadows, the shadow will no longer appear directly beneath the image. With borders, they will be fully opaque.

            If images are opaque, then the best option is to use "Same as image" option as this will preserve the anti-aliasing that image-edges sometimes have.

            With effects such as Rad Wave and Jagged Edge, where the border lines are curved and not a straight edge, the "Same as image" option is typically the best choice for shadows. This is again, caused by the anti-aliasing, which will make glowing edges if the shadow is "Made Opaque".

        Intensity

            Changes a shadow's appearance by making the shadow either lighter or darker.

        Invert

            When checked, the colors are inverted, like a negative.

        Keep the Gradient

            When this checkbox is checked, GIMP will save the resulting gradient from an Image Gradient operation to the user's gradient folder. However, the gradient isn't saved (with a .ggr file-type in Windows) to the storage device until GIMP is shutdown. However, the gradient will be available in the gradient tab. You may have to move focus to another window tab for the new gradient to appear in the gradient list.

        Light Angle

            This angle will change how the emboss effect will appear on a border. The source of the light will make one edge appear brighter than the mesh's opposing side.

        Line Gap

            Is the space between the lines that form the bars in the Line Fashion frame.

        Line Width

            In Rad Wave and Maze Mirror, line width is the width of the composition mesh. In Line Fashion, line width is the span of the line that forms the frame-bars.

        Maze Type

            There are four maze types:
            ￭ Border draws mazes around the edges of the image.

            ￭ Filled draws mazes in every cell.

            ￭ Scattered Connectors will draw a horizontal or vertical line in cells. The direction of the rotation will effect the connector's orientation.

            ￭ Scattered Mazes will draw a mazes in cells.

            In the scattered types, the cells chosen are effected by the gap type and the cell gap.

        Mesh Size

            This is the size of the mosaic tile used by the style or effect.

        Mesh Type

            These are mosaic patterns that are used to form border meshes or backdrop patterns.

        Mode

            This is a blend mode applied to a style after it's been generated. The style will blend with the backdrop image.

        Name

            This will be the name of the resulting gradient of an Image Gradient operation. It is only relevant if Keep the Gradient is checked.

        Neatness

            This value will range from 0 to 1. At one, the pattern will be orderly and neat. At zero, the pattern is chaotic.

        Noise Settings
            Seed

                Changing this value will produce a different noise pattern.

            Power

                Increasing this value creates more noise.

        Offset

            Extends the Start X and Start Y points by this measurement. With gradients, higher offsets make a gradient look stretched at its origin.

        Offset X, Y

            These refer to how many pixels away from the image a shadow should appear. Changing the offsets changes the influence of the light-source.

        Opacity

            This value influences a blend where one layer is merged with another. The upper layer's opacity can be altered with this setting.

        Paint Mode

            These are blend modes that a tool uses to spread matching criteria pixels.

        Pane Width, Pane Height

            This is the scale of the Stained Glass colored rectangles before they are rotated.

        Pattern

            This is a list of available patterns found in the GIMP installation.

        Reverse

            When checked, a gradient's color segments are displayed in reverse order. Thus, in the gradient, the end becomes the start and vice-versa.

        Rotate

            This value rotates a layer around the center of the image after it's drawn. The values are in degrees.

        Rounded Edge Blur

            This is the same blur as as inlay shadow blur. The greater the value the higher the image will appear.

        Round Up

            The rounded edge blur color will be white if this option is selected. This makes the edge look like it's curved upwards. Otherwise, the a black color is used which has the opposite effect making the image edge appear rounded down.

        Row and Column Spin Buttons

            These are grid-related numeric entries. Rows divide the vertical space and columns divide the horizontal.

        Sample Points

            These are evenly placed points along a vector where the backdrop image's color is sampled. They are scaled by Sample Radius. Each sample will include transparency if any.

        Sample Radius

            This is the size of a circle of pixels used in a color sampling. The final pixel color is averaged from these pixels.

        Scatter Count

            The number of connectors or mazes to place. In the case of Evenly Distributed placements, the same cell may be selected twice for a given placement as Roller will repeatedly cycle through the cell block until assigning this scatter count.

        Shadow Blur

            This is the amount of blur effect to apply to a shadow. The greater the blur, the softer the shadow.

        Start And End X, Y

            These are points where gradients start and end. Pattern and Color Fill use this point as a source of origin to spread their applications. The points are limited to the image size.

        Stop Length

            When the length of a maze line segment falls below this value, the maze will stop drawing inwards.

        Texture

            This option causes the Rainbow Valley output to have a fabric-like texture.

        Threshold

            Lower values will lower the number of matching colors for a color-dependent criteria. Higher values will increase the appearance of an effect.

        Vector

            This is a virtual line that can be drawn from one side of an image to its opposite side or corner. This vector defines where Sample Points are located.

        Whirl

            This value will spin the Rad Wave effect around the center of the image.

Errors And Limitations To Be Aware Of

    ￭ Opening and closing images in GIMP while the plug-in is running will likely make it unstable.

    ￭ Putting too many rows and columns into a composition may result in a crash. GTK has its limitations, and Roller doesn't compensate. Right now I just tried a 100 rows by 100 columns, and GTK appears to be stuck drawing the window. That would be 10,000 cells, so no wonder.

    ￭ I recommend having the Layer Dock visible while running the plug-in as this dock will show GIMP working as the plug-in is running.

    ￭ Inlay and edge shadows will not produce a shadow for an image-side if it's lies directly on a side of the render.

    ￭ In the option dialogs, a preview will be used as part of a render if it corresponds with the option settings.

    ￭ I recommend naming the format layers where no two formats have the same name.

    ￭ Roller uses a variety of Unicode characters as layer keys and will remove these characters from a Format name if they are applied by the user.

    ￭ Only use one opened Roller script at a time. Two running Roller scripts will likely crash into each other.

    ￭ When the script is run for the first time, Python creates ".pyc" type files within the "roller" modules. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so no worries about deleting them.

    ￭ Light Shaft, Spacetime Fabric, and Honey Bee backdrop styles are not reproducible with Auto: Last Used. They reproduce a close rendition.

    ￭ When using "Auto: Last-Used" with multiple layers, a render may differ from a manual-render if both layers are using the same effect. This happens because Roller keeps only one last-used effect-settings for both layers.

Tips

    ￭ The backdrop style, Spacetime Fabric, needs a backdrop image that has more than one color.

    ￭ Backdrop styles can apply their material to images with transparency while leaving the transparency intact.

    ￭ The Jagged Edge effect will look better if its drop shadow Inherit Opacity setting is set to "Same as Image".

Links

    I post the latest version of my GIMP plug-ins on GitHub under my GummyCowboy user-name:
        github.com/gummycowboy

    I have a thread on GimpLearn which you can use to give feedback:
        gimplearn.net/viewtopic.php?f=3&t=2805&p=33090#p33090

    These are GIMP-related sites worth visiting:
        For Users
            gimplearn.net
            gimpchat.com
            www.gimp-forum.net
            www.gimpusers.com
            www.gimpscripts.net
            gimp.1065349.n5.nabble.com

        For Developers
            gimp.1065349.n5.nabble.com/Developers-f15145.html

        Get GIMP ("GNU Image Manipulation Program")
            www.gimp.org

Special Thanks

    Many thanks to the free programs Notepad++, Visual Studio Code, and PyCharm for being a great Python code editors. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their work.